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[ COMMON 
COMPONENT 
SYMBOLS ] 


>RESISTOR 


>BUTTON/ 
SWITCH 


>CAPACITOR 


he Raspberry Pi is great for learning computing. Whether 
that’s coding or tricks for the advanced user, the Raspberry 

Pi has many tools to help you learn about them. It’s also very 
good at physical computing, which in this context means programming 
and interacting with the real world through electronics. In simple 
terms, physical computing with the Pi is something like programming 
itto turn on an LED, a component in an electronic circuit. 

The electronic circuits are the physical part of a physical computing 
project connected to the Raspberry Pi. These circuits can be simple 
or very complex, and are made up of electronic components such as 
LEDs, buzzers, buttons, resistors, capacitors, and even integrated 
circuit (IC) chips. 

At its simplest, an electronic circuit lets you route electricity to 
certain components in a specific order, from the positive end of a 
circuit to the negative (or ground) end. Think of a light in your house: 
the electricity passes through it, so it lights up. You can add a switch 
that breaks the circuit, so it only lights up when you press the switch. 
That is an electronic circuit. 


Reading circuit diagrams 

Building a circuit can be easy if you know what you're doing, but if 
you're making a new circuit or are new to electronics in general, you'll 
most likely have to refer to a circuit diagram. This is a common way 
you'll see a circuit represented, and these diagrams are much easier to 
read and understand than a photo of a circuit. However, components 
are represented with symbols which you'll need to learn or look up. 
Fig 1 is an example of the light circuit we talked about before. Here we 
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Fig 1 Switch circuit 
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Eachholeona 
numbered row is 
connected to each 
other, with a split in 
the middle where 
the groove is 


This part of the 
breadboard is connected 

all the way across, as the lines 
indicate. They're often used to 
provide an easily accessible positive 
and negative 'rail 


have a power source (a battery in this circuit), a switch, a resistor, and 
an LED. The lines represent how the circuits are connected together, 


either via wire or other means. Some components can be used any 
way round, such as the resistor or switch. However, others have a 
specific orientation, such as the LED. Diodes only let electricity flow 
from positive to negative; luckily, real-life LEDs have markers such 
as longer legs or a flat edge to indicate which side is positive, making 
them easier to wire up. 


The Raspberry Pi and electronic circuits 
П | Making а Raspberry Pi part of the circuit is quite easy. At its most basic, 
it can provide power to a circuit, as well as a negative or ground end 
through the GPIO pins. Some pins are specifically always powered, mostly 
by 3.3V, and always go to ground. Most of them can be programmed to 
create or recognise a HIGH or LOW signal, though; in the case of the 
Raspberry Pi, a HIGH signal is 3.3V and a LOW signal is ground or oV. 
In an LED example, you can wire up an LED directly to a 3.3V pin and 
a ground pin and it will turn on. If you instead put the positive end of 
the LED onto a programmable GPIO pin, you can have it turn on by 
making that pin go to HIGH (see chapter 2 for more details). 
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Wiring up a circuit to a Raspberry Pi is fairly simple. To create the 
physical circuits in the guides throughout this book, we're using 
prototyping breadboards. These allow you to insert components 
and wires to connect them all together, without having to fix them 
permanently. You can modify and completely reuse your components 


because of this. 


[ GPIO NUMBERS ] 


40-pin GPIO header key for 
Raspberry Pi 3, 2, B+, and A+ 


GPIO Zero uses the BCM GPIO numbering rather 
than the pin number - use this handy table 


to remember which is which 
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can install GP 
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hooked up to your Raspberry Pi, you 
need to be able to control them. The 
Raspberry Pi is set up to allow you to 

h the Python language. 
een made simpler recently 
on of GPIO Zero. It comes 
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pre-installed in the latest ve 


on't have it ye 


a package list update by ente 


get updateina 
install python 
GPIO Zero was created to si 


of physical computing, helpi 
learn. It's a Python library which builds upon the 


existing GPIO 


This change 
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state when the 


However, while t 


computing. Consid 


configured with a p 


libraries RPi.G 


O Zero manually: after performing 


terminal, enter sudo apt-get 
3-gpiozero. 


rsion of Raspbian 
t, however, you 


ring sudo apt- 
mplify the process 
ng new coders to 


PIO, RPIO, and pigpio. 


hose libraries provide an interface 
to the GPIO pins themselves, GPIO Zero sits above 

them and provides a way to i 
that you conne 


nterface to the devices 


ct to those pins. 

simplifies thinking about physical 

er wiring a simple push button 

to GPIO 4 and ground pins. In order to react to this 

d to know that the pin should be 

ull up resistor, and that the pin 
button is pushed will be o. Here's what 
this would look like in the classic RPi.GPIO library: 
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GPIO.setmode (GPIO.BCM) 


GPIO.setwarnings (False) GPIO Zero can use buttons, 
GPIO.setup(4, GPIO.IN, GPIO.PUD_UP) LEDs, buzzers, and lots of other 
GPIO.input(4): components. The library is 


always expanding. 


To complete beginners, there’s quite a lot 
going on there, which gets in the way of actually 
experimenting with it and even teaching the 
simple logic required. Here's the equivalent code 
in GPIO Zero: 


gpiozero Button 


btn = Button(4) 
btn.is_pressed: 


The boilerplate, the code you have to blindly 
enter without understanding why you’re entering 
is reduced to the bare minimum that we need. 
[he name ‘GPIO Zero’ derives from this ‘zero 
boilerplate’ philosophy, which was first espoused 
by Daniel Pope’s Pygame Zero library. 

The logic is also straightforward, with 

no curious inversion of the input value. 
So, now you’ve learnt about GPIO 
Zero and how it makes coding much 
impler, it’s time to get started doing 
some physical computing with 

it. In chapter 2, we'll show you 
how to wire up some LEDs on a 
breadboard and control them 
using GPIO Zero's LED class. 
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GPIO Zero 


1x solderless 
breadboard 


3x LEDs (red, 


yellow, green) 


3x 3302 resistors 


4x male-to- 
female jumper 
wires 


Or a Traffic HAT 
magpi.cc/ 
1Mma7oD 


e Aresistor is 
required to limit the 
amount of current 
being drawn by 

the LED, to avoid 
damage to the Pi 


* TheLED's longer 
leg is wired to GPIO 
25, while the other 
is connected via 
aresistor to the 
ground rail 


ne of the first physical computing projects you'll want to 

try with GPIO Zero is lighting an LED. This is very simple to 

achieve using the library's LED class, using very few lines of 
code. Here we'll show you how to wire up a simple circuit connected to 
your Raspberry Pi's GPIO pins, then light an LED and make it blink on 
and off. We'll then add two more LEDs to make a traffic light system, 
or you can also use a special Traffic HAT add-on. 


>STEP-01 

Connect an LED 

It's best to turn the Pi off when building a circuit. The breadboard 
features numbered columns, each comprising five connected holes. 
Place your red LED's legs in adjacent numbered columns, as shown in 
the diagram. Note that the shorter leg of the LED is the negative end; 
in its column, insert one end of the resistor, then place the other end 
in the outer row marked ‘-’ (the ground rail). Use a male-to-female 
jumper wire to connect another hole in that ground rail to a GND pin 
on the Pi. Finally, use a jumper wire to connect a hole in the column 
of the LED's longer (positive) leg to GPIO pin 25. 
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>STEP-02 


% 
“ 
“ 
a 
LI 
t 
г 


Above While it's 
possible to connect 


Light the LED an LED and resistor 
We'll now test our circuit with a simple Python program to make the B 
ED turn on and off. To start coding, open IDLE from the Main Menu: use a solderless 
breadboard 


Menu > Programming > Python 3 (IDLE). Create a new file by clicking 
File > New file. Save it with File > Save, naming it ch2listing1.py. Now 
enter the code from the listing of the same name (page 16). 

At the start of the program, we import the LED class from GPIO Zero, 
and the sleep function from the time library (to enable us to pause 
between turning the LED on and off). We then assign the led variable 
to the GPIO 25 pin, which will power it whenever we set it to on in 
the code. Finally, we use while True: to create a never-ending loop 
that switches the LED on and off, pausing for 1 second between each 
change. Press F5 to run the code, and your LED should be flashing on 
and off. To exit the program, press CTRL+C. 


>STEP-03 | В E 


Easier blinking 


Alternatively, to make things even easier, GPIO Zero features a special 
blink method. You could try entering the code from ch2listing2.py | | il 


(page 16), which does exactly the same thing as the first listing, but 
with even fewer lines of code. 
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Each LED's longer leg is wired to the 
respective GPIO pin, while the other is 
connected via a resistor to the ground rail 


Aresistor is required to limit the amount 
of current being drawn by each LED, to 
avoid damage to the Pi 


Each LED circuit shares a common 
ground via the '-' rail, which is 
connected to a GND pin on the Pi 


Note that between the brackets 
for led.blink, you can add 
parameters to set the on and off 
times, number of blinks, and 
determine whether it runs as 
a background thread or not. 


>STEP-04 

Add more LEDs 

Now that we’ve got the hang of 
controlling one LED, let’s add 

a few more and create a traffic 
light sequence. You can add an 
optional push button to control it 
if you like, but for now we'll stick 
to just the LEDs. Connect them as 
shown in the diagram, with the 


longer (positive) legs connected via jumper wires to the following GPIO 
ins: 8 (yellow), and 7 (green). As before, we need a resistor for each 
ED, which shares a common ground connection via the ‘-’ rail to one 
of the Pi's GND pins. 


>STEP-05 

Enter the code 

After opening Python 3 (IDLE), type in the code from chalisting3.py 
(page 17) and save it. As before, we import the LED class and sleep 
function from GPIO Zero and the time library respectively. We then 
assign red, amber, and green variables to the relevant GPIO pins. 
To start with, we turn the green LED on and the others off. Finally, 
we use while True: for a never-ending loop; this waits 10 seconds 
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before showing amber then red, then waits another 10 seconds 
before showing red/amber then green. Press F5 to run the program 
and wait for the traffic light sequence to start. 

Rather than using sleep to create a delay between each sequence, 
you could trigger it with the addition of a push button: see chapter 3 
for more details. You could also use a Traffic HAT with a built-in push 
button, LEDs, and buzzer. 


>STEP-06 

Traffic HAT 

The Traffic HAT is a fun little kit and has its own 
GPIO Zero class for easy programming. With your 
Raspberry Pi turned off, slot the Traffic HAT over the 
GPIO pins, with the board itself lying across the Pi. 
Open a new file in Python 3 IDLE, enter the code from 
ch2listing4.py (page 17), and save it. At the top, we 
import the TrafficHat class, along with the sleep one from the time Pove 
library. We then use a while True: loop to control the traffic lights. si 
The green light is lit until the button is pressed, then the sequence 
is triggered; when it reaches red, the buzzer beeps 20 times, as on a 
pedestrian crossing. Amber then flashes, before it returns to green 
at the start of the loop, awaiting the next button press. 


Magi 
ESSENTIALS 


SE düliing.py ch2listingd.py 


from gpiozero import LED from gpiozero import LED 
from time import sleep from time import sleep 
led - LED(25) red - LED(25) 
amber = LED(8) 
while True: green = LED(7) 
led.on() 
sleep(1) green.on() 
led.off() amber.off() 
sleep(1) red.off() 
while True: 
У Я 51еер(10) 
ch2listing2.py green. off() 
amber .on() 
from gpiozero import LED sleep(1) 
from signal import pause amber. of F() 
red.on() 
red = LED(17) sleep(10) 
amber.on() 
red.blink() sleep(1) 
green.on() 


pause() amber .off() 


red.off() 
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ch?ü Li 4.Dy I >PYTHON 3 


DOWNLOAD: 
from gpiozero import TrafficHat magprcc/2bhwguz 
from time import sleep 


th = TrafficHat() 
try: 
while True: 
# Traffic light code 
# First, turn the green LED on 
th.lights.green.on() 
print("Press the button to stop the lights!") 
# Next, we want to wait until the button is pressed 
while(th.button.is_pressed == False): 
# While not pressed, do nothing 
pass 

# Button has been pressed! 
th.lights.green.off() 
# Amber on for a couple of seconds 
th.lights.amber.on() 
sleep(2) 
th.lights.amber.off() 
# Turn the red on 
th.lights.red.on() 
# Buzz the buzzer 20 times with 0.1 second intervals 
th.buzzer.blink(0.1,0.1,20,False) 
sleep(1) 
th. lights -red off) 
# Red off and blink amber 4 times with 0.5 second intervals 
th.lights.amber.blink(0.5,0.5,4,False) 


except KeyboardInterrupt: 
exit() 
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CHAPTER THREE 
ADD USER INPUT 


Make things happen at the press of a button 
and create a fun two-player reaction game 


» GPIO Zero 


> 1x solderless 
breadboard 


> 2x push buttons 
»1x LED 
> 1x 3300 resistor 


» 4x male-to- 
female jumper 
wires 


» 2x male-to-male 
jumper wires 


s well as output devices such as LEDs and buzzers, the 

Raspberry Pi's GPIO pins can be linked to input devices. One 

of the most basic is a simple push button, which can be used to 
trigger other components or functions. First, we'll hook up a button on 
a breadboard and get a program to print a message on the screen when 
it's pushed. We'll then get it to light an LED, before adding a second 


button for a fun two-player reaction game. 


>STEP-01 

Connect the button 

It's advisable to turn the Pi off when building your circuit. Note: if 

you've already completed chapter 2, you can leave your breadboard 

circuit as it is, but here we'll assume you're building a new circuit. 
Add the push button to the breadboard, as in the diagram, with its 

pins straddling the central groove. Connect a male-to-female jumper 

wire from one pin's column to GPIO pin 21 on the Pi. Then connect a 


Raspberry Pi 3 Model B v1.2 
© Raspberry Pi 2015 


ETHERNET 


Whenthe — male-to-male jumper wire from the other pin (on the same side of 
button is pressed, (3 ; A 
GPIO 21 registers Ше groove) to the *— ground rail. Finally, connect a male-to-female 


the low signaland jumper wire from the latter to a GND pin on the Pi. 
our program turns 


the LED on 


Button pushed 
We'll now test our circuit with a simple Python program to show a 
message on the screen whenever the button is pushed. To start coding, 
open IDLE from the Main Menu: Menu > Programming > Python 3 
(IDLE). Create a new file by clicking File » New file. Enter the code from 
ch3listing1.py (page 23), then save it. 
At the start of this short program, we import the Button class from 
GPIO Zero. We then assign the button variable to the GPIO 21 pin, so 
we can read its value. Finally, we use while True: to create a never- 
ending loop that checks whether the button has been pressed or not, 
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and prints a status message on the screen. When you run the code 
with F5, you'll get a scrolling list of messages that change when 
you press the button. To exit the program, press CTRL+C. 

Note that it's also possible to trigger a Python function when 
the button is pressed, using the following syntax: 


button.when pressed - functionname 


>STEP-03 

Wait for it 

GPIO Zero’s Button class also 
includes a wait for press 
method which pauses the script 
until the button is pressed. Open 
a new file in Python 3 IDLE, enter 
the code from ch3listing2.py 
(page 23), and save it. This will 
only print the message at the 
bottom on the screen once the 
button has been pressed. The 
program is then ended. 


>STEP-04 

Light an LED 

Add a red LED to your breadboard, 
using jumper wires to connect its 
longer leg to the GPIO 25 pin, and 
its shorter leg via a resistor to the 
ground rail; your circuit should 
resemble the diagram on page 19. 
In a new Python 3 IDLE file, enter 
the code from ch3listing3.py and 
save it. At the top, we import 

the LED and Button classes 

from GPIO Zero, along with the 
pause function from signal. 

We then allocate variables to the 


After a random 
time, the LED is lit 
and the first person 
to hit their button is 
the winner 


A second push 
button is added for 
the reaction game; 
when pressed, GPIO 
2is pulled low 
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ESSENTIALS 


Right 


LED and button on GPIO pins 25 and 21 respectively. When the button 
is pressed, the LED is turned on; when released, it's turned off. 

It's also possible to keep the LED lit for a set period after pressing. 
Open a new file, enter the code from ch3listing4.py (page 24), and save 
it. This time, we wait for a button press as in step 3, then turn the LED 
on for three seconds, then off. 


>STEP-05 

Reaction game 

By adding а second push button to our circuit, we can make a simple 
two-player reaction game. When the LED turns on at a random time, 
the first person to hit their button is the winner. Position the extra 
button on the breadboard as in the diagram on page 21, connecting it 
to the ground rail and GPIO 2; move the LED and its connections to the 
middle, if not there already. Open a new file in Python 3 IDLE, enter 
the code from ch3listing5.py (page 24), and save it. At the top, we 
import the classes required as before, along with the random module. 
We assign variables to the LED and two buttons, then create a time 
variable equal to a random number between 5 and 10; after sleeping for 
this number of seconds, the LED is turned on. The while True: loop 
is terminated with break when someone presses their button, after 
printing the appropriate victory message. 
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chölistingl.py 


from gpiozero import Button 
button = Button(21) 
while True: 
if button.is_pressed: 
print("Button is pressed") 


else: 
print("Button is not pressed") 


chóliating2 
listing2.py 
from gpiozero import Button 


button = Button(21) 


button.wait_for_press() 
print("Button was pressed") 


chölistingd.py 


from gpiozero import LED, Button 
from signal import pause 


led = LED(17) 
button = Button(21) 


button.when_pressed = led.on 
button.when_released = led.off 


pause() 


qanguage 


>PYTHON 3 


DOWNLOAD: 
magpi.cc/2bhwcLz 
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chölistingt.py 
from gpiozero import LED, Button 


from time import sleep 


led = LED(25) 
button = Button(21) 


button.wait for press() 
led.on() 
sleep(3) 
led.off() 


chóliatingo.py 


from gpiozero import Button, LED 
from time import sleep 
import random 


led - LED(25) 


player 1 
player 2 


Button(21) 
Button(2) 


time - random.uniform(5, 10) 
sleep(time) 
led.on() 


while True: 
if player 1.is pressed: 
print("Player 1 wins!") 
break 
if player 2.is pressed: 
print("Player 2 wins!") 
break 


led.off() 
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CHAPTER OUR 


MAKE A PUSH BUTTON 


MUSIC BOX 


ПЕС 


Magi 


—— — : o far, we've added a push button to a simple circuit to light an 
LED, and then added a second button to make a reaction game. 
In this chapter, we'll use several push buttons to make a GPIO 
music box that triggers different sounds when we press different buttons. 
GPIO Zero For this, we'll make use of GPIO Zero's Button class again, as well as using 


РА the Python dictionary structure to assign sounds to buttons. 


breadboard 


2x push buttons 


Get some sounds 


x male-to- Кер r 7 Л 
е Before we start building our GPIO music box circuit, we'll need to 
female jumper . . d ) 
wires prepare some sound samples for it to play. First, open a terminal 
ЖЕСЕ window and create a new folder called musicbox for this project: mkdir 
jumper wires musicbox. Then change to that directory: cd musicbox. Now we need 
Headphones to source some sound samples. While there are many public domain 
or speaker sounds to be found online, for this example we'll use some of Scratch's 


Each time you 
press a button, 

the assigned 
sound sample will 
play through a 
connected speaker 


77 


"Te: 
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built-in percussion sounds, already present on the Pi. In your 
terminal, enter mkdir samples, then change to that directory: 
cd samples. Now copy the Scratch percussion sounds with: 


cp /usr/share/scratch/Media/Sounds/Percussion/* . 


>STEP-02 

Play a drum 

We'll now create a simple 
Python program to play a drum 
sample repeatedly, to check 
everything is working. Open IDLE 
from the Main Menu: Menu » 
Programming » Python 3 (IDLE). 
Create a new file by clicking File 
» New File. Now enter the code 
from the listing chalisting1.py 
(page 30), changing the WAV file 
name to suit your own sample if 
you're using different ones. Save 
the file in your musicbox folder 
with File > Save. 

At the start of the program, 
we import the mixer module 
from the Pygame library, then 
its Sound class which enables 
multichannel sound playback 
in Python. Next, we add a line 
to initialise the Pygame mixer: 
pygame.mixer.init(). Wethen 
create a Sound object for one of 
the files in our samples folder: 
drum = Sound("samples/ 
DrumBuzz .wav"). 

Finally, we add awhile True: 
loop to repeatedly play the 
drum sound. Press F5 to run 


++... 
..... 


...ӛ.. 
eevee 


Extra 

buttons can easily 
be added to the 
circuit to play more 
sounds assigned in 
the Python code 


the program and listen to it play. If you can't hear it, you might need 
to alter your audio configuration; in a terminal, enter amixer cset 
numid=3 1 to switch it to the headphone socket, or amixer cset 
numid=3 1 to switch to the HDMI output. 


Wire up a button 
As usual, it's best to turn the Raspberry Pi off while connecting our 
circuit on the breadboard. First, we'll add a single button. As before, 
place the button so it straddles the central groove of the breadboard. 
One leg is connected to GPIO pin 2, and the other to the common 
ground rail on the breadboard, which in turn is wired to a GND pin. 
We'll now make a sound play whenever the button is pressed. 
Open a new file in Python 3 IDLE, enter the code from chalisting2.py 
(page 31), and save it in your musicbox folder. At the start of the 
program, we also import the Button class from GPIO Zero, and 
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the pause class from the signal library. We assign the button 
variable to GPIO pin 2, with button - Button (2). We then tell the 
sound to play when the button is pressed: 


button.when pressed - drum.play 


Finally, we add pause() at the end so that the program will continue 
to wait for the button to be pressed. Run the program and every time 
you press the button, the drum sound should play. 


>STEP-04 

Add a second button 

We'll add a second button to the circuit, so it should now look like the 
diagram on page 27. Place it on the breadboard as before, and wire it up 
to GPIO 3 and the common ground rail. Now open a new file in Python 
3 IDLE, enter the code from chalisting3.py (page 31), and save it in your 
musicbox folder. Note that rather than assigning the Button objects 
and sounds to the pins individually, we're using a dictionary structure 
to assign their numbers to sound samples: 


sound pins - ( 


2: Sound("samples/DrumBizz.wav"), 
3: Sound("samples/CymbalCrash.wav"), 


We then create a list of buttons on all the pin numbers in the 
sound pins dictionary: 
buttons - [Button(pin) for pin in sound pins] 


Finally, we create a for loop that looks up each button in the 
dictionary and plays the appropriate sound: 


for button in buttons: | А E 


sound - sound pins[button.pin.number] 
button.when pressed - sound.play | | ЕЕ 
Run the program and press each button to hear a different sound. 
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>STEP-05 

Add more buttons 

The way we have structured the program makes it easy to add extra 
buttons and assign them to sound samples. Just connect each button to 
a GPIO number pin (not any other type) and the ground rail, as before. 
Then add the GPIO pin numbers and sounds to the dictionary, as in the 
following example: 


sound_pins = { 
2: Sound("samples/DrumBizz.wav"), 
3: Sound("samples/CymbalCrash.wav"), 
4: Sound("samples/Gong.wav"), 
14: Sound("samples/HandClap.wav"), 


E TI 
chHistingl.py 


import pygame.mixer 
from pygame.mixer import Sound 


pygame.mixer.init() 
drum = Sound("samples/DrumBuzz.wav") 


while True: 
drum.play() 
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chlisting2.py 


from gpiozero import Button 
import pygame.mixer 

from pygame.mixer import Sound 
from signal import pause 


pygame.mixer.init() 
button = Button(2) 
drum = Sound("samples/DrumBuzz.wav") 


button.when pressed = drum.play 
pause() 


ch'flisting3.py 


from gpiozero import Button 
import pygame.mixer 

from pygame.mixer import Sound 
from signal import pause 


pygame.mixer.init() 


sound_pins = { 

2: Sound("samples/DrumBuzz.wav"), 

3: Sound("samples/CymbalCrash.wav"), 
} 


buttons = [Button(pin) for pin in sound_pins] 
for button in buttons: 
sound = sound_pins[button.pin.number] 
button.when_pressed = sound.play 


pause() 


qanguage 


>PYTHON 3 


DOWNLOAD: 
magpi.cc/2bhwqlH 
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CHAPTER — 
MEASURE 
CPU USAGE 
AN “RGB LED 


e lit up a standard LED in chapter 2, using GPIO Zero's LED 
class. It also features a special RGBLED class for controlling - 
guess what - an RGB LED! In this chapter, we'll make use of 
this to light up our LED in different shades by altering the red, green, 
and blue values. Then we'll code up a little program that tracks the 
» GPIO Zero Pi's CPU usage percentage, and adjust the LED between green and red 
accordingly to show how much processing power it's using. 


> 1x solderless 
breadboard 


> 1x RGB LED >STEP-01 
Select your RGB LED 
Light-emitting diodes (LEDs) are cool. Literally. Unlike anormal 

2 ee incandescent bulb, which has a hot filament, LEDs produce light solely 

vres by the movement of electrons in a semiconductor material. An RGB LED 
has three single-colour LEDs combined in one package. By varying the 
brightness of each component, you can produce a range of colours, just like 
mixing paint. There are two main types of RGB LEDs: common anode and 
common cathode. We're going to use common cathode for this project. 


> 3x 1002 resistor 


limit 


ETHERNET 


ESSENTIALS 


Below 


>STEP-02 

Connect the RGB LED 

As usual, it’s best to turn the Raspberry Pi off while connecting our 
circuit on the breadboard. LEDs need to be connected the correct way 
round. For a common cathode RGB LED, you have a single ground 
wire - the longest leg - and three anodes, one for each colour. To 
drive these from a Raspberry Pi, connect each anode to a GPIO pin via 
a current-limiting resistor. When one or more of these pins is set to 
HIGH (3.3V), the LED will light up the corresponding colour. Connect 
everything as shown in the diagram on page 33. 

Here, we wire the cathode (long leg) to a GND pin, while the other 
legs are wired via resistors to GPIO 14, 15, and 18. The resistors are 
essential to limit the amount of current flowing to the Pi, to avoid 
damaging it; we've used 1000 resistors, but you could get away with 
using ones with a slightly higher ohmage, such as 3300. 
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Here we're 
monitoring the 

Pi's CPU usage; 
yellow means it's at 
about 50% 


Test the LED 

With the RGBLED class in GPIO Zero, it's easy to alter the colour 

of the LED by assigning values of between o and 1 to red, green, 

and blue. On the Pi, open IDLE from the Main Menu: Menu > 
Programming » Python 3 (IDLE). Create a new file by clicking File 

> New file, then enter the code from ch5listing1.py (on page 37) 

and save it. 

At the top, we import the RGBLED class from GPIO Zero, along 
with the sleep function from the time library. We then assign the 
variable led to the RGBLED class on GPIO pins 14, 15, and 18, for red 
green, and blue. We then make led. red equal to 1 to turn the LED 
a full red colour. After a second, we then change the value to 0.5 | | 


2 


to reduce its intensity. We then go through a sequence of colours 
using led.color, assigning it a tuple of red, green, and blue values 
to mix the shades. So, (1, 0, 1) shows full red and blue to make 
magenta. You can vary each value between o and 1 to create an 
almost infinite range of shades. Finally, we use a for loop to slowly 


increase the intensity of blue. 
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>STEP-04 

Add a new library 

We now want to get our RGB LED to change colour between green and 
red, to show the CPU usage of the Raspberry Pi to which it’s connected, 
so we can track how much of its processing power we’re using at any 
time. For this, we'll need the psutil library, which can be installed 
from the terminal with: 


sudo pip3 install psutil --upgrade 


This will let us look up the CPU usage of the Raspberry Pi asa 
percentage number, which can then be used in our code to vary 
the LED's colour. 


>STEP-05 

Measure CPU usage 

n IDLE, create a new file, enter the code from ch5listing2.py, and save 

it. At the top, we import the modules we need, including psutil. We then 
assign the myled variable to the RGBLED class on GPIO 14, 15, and 18, for 
red, green, and blue. In a never-ending while True: loop, we assign the 
cpu variable to the percentage of CPU usage via psutil, then assign the 
red and green LED values accordingly, and light the LED. 

Try running the code. The LED should light up: its colour will indicate 
how hard your Pi's CPU is working. Green means less busy, turning 
redder as the CPU becomes more heavily loaded. Start up some other 
applications to test it. If you have an original Model B, you'll probably 
find that just running Minecraft is enough to turn the LED red. If you 
have a Pi 3, you may need to start lots of things running in order to 
have any impact! 


>STEP-06 

Customise your project 

The example code only uses the red and green components ofthe LED: 
the blue value is always set to zero. You could swap things around and 
create a different colour gradient (e.g. blue to red), or put together a 
fancy function that maps a percentage value onto all three colours. 
Have fun with the colours and maybe even have it look at other 
resources to monitor... 
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choliatingl.py 


from gpiozero import RGBLED 
from time import sleep 


led - RGBLED(14,15,18) 


led.red = 
sleep(1) 
led.red = 
sleep(1) 


led.color 
sleep(1) 
led.color 
sleep(1) 
led.color 
sleep(1) 
led.color 
sleep(1) 
led.color 
sleep(1) 


led.color 
sleep(1) 


al 


0 


# full red 


.5 # half red 


(9, 
(1, 
(1, 
(9, 


(1, 


(9, 


e, 


e) 
1) 
e) 
1) 


1) 


9) 


# full green 
# magenta 

# yellow 

# cyan 


# white 


# off 


# slowly increase intensity of blue 
for n in range(100): 
led.blue = п/100 
sleep(®.1) 


qanguage 


>PYTHON 3 


DOWNLOAD: 
magpi.cc/2bhwsdc 


cholisting2.py 


from gpiozero import RGBLED 
import psutil, time 


myled = RGBLED(14,15,18) 


while True: 
cpu = psutil.cpu percent() 
r = cpu / 100.0 
g = (100 - cpu)/100.0 
b= ð 
myled.color = (r, g, b) 
time.sleep(0.1) 


[ Measure CPU Usage with an RGB LED] MägPi | 37 


M The П 
ESSENTIALS / 


CHAPTER > >. 


МАКЕ А 


MOTION- 


SENSING 
ALARM 


Stop people from sneaking up on your stuff by 
creating a motion-sensing alarm that buzzes 
when it detects someone 
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1х HC-SR501 
PIR sensor 
magpi.cc/ 
ırwsEL7 


1x Mini piezo 
buzzer 
magpi.cc/ 
arwsXG2 


Jumper wires 


While the PIR is 


powered by 5V, its 
output is 3.3V so no 
resistor is required 


eed to protect your room or precious items from miscreants 

or nosy family members? With just a PIR motion sensor and a 

buzzer wired up to your Raspberry Pi, it’s very simple to create 
an intruder alert. Whenever movement is detected in the area, a loud 
beeping noise will raise the alarm. To take things further, you could 
add a flashing LED, an external speaker to play a message, or even a 
hidden Camera Module to record footage of intruders. 


>STEP-01 

Attach PIR motion sensor 

First, we need to wire the PIR (passive infrared) sensor to the Pi. 
While it could be hooked to the GPIO pins directly using female-to- 
female jumper wires, we're doing it via a breadboard. The sensor has 
three pins: VCC (voltage supply), OUT (output), and GND (ground). 
Use female-to-male jumpers to connect VCC to the “+ rail of the 
breadboard, and GND to the <>? rail. Wire OUT to a numbered row, 
then use another jumper to connect that row to GPIO pin 4. 


The PIR sensor 
detects motion via 
changes in the levels 
of infrared radiation 


The mini piezo 

buzzer beeps an 
audible alarm when 
motion is detected 


13N33H13 


© Raspberry Pi 2014 


(AVIdSID) IST 
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program uses an А 
и loopto Wire up the buzzer 
tect motion, a A 
illa kohust Next, we'll hook up the mini buzzer. Place its two legs across the central 
beep 4. groove in the breadboard. Note that the longer leg is the positive pin; wire 
that : A ; npe 
arocens its numbered row to GPIO pin3on the Pi to connect it. Wire the row of the 
buzzer's shorter leg to the “— rail, then connect the latter to a GND pin on 


the Pi. Finally, connect the ‘+’ rail to the Pi's 5V pin to power the PIR sensor. 


Work on the code 

In IDLE, enter the code from chólisting1.py. At the start, we import 
the MotionSensor and Buzzer modules from GPIO Zero, each of which 
contains numerous useful functions; we'll need a few of them for our 
intruder alarm. We also import the time library so that we can add a 
delay to the detection loop. Next, we assign the relevant GPIO pins for 
the PIR sensor and buzzer; we've used GPIO 4 and 3 respectively in this 
example, but you could use alternatives if you prefer. 
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qanguage 


>STEP-04 


Setting things up chóliatingl pu 
Before starting our motion 4 


detection while loop, we from gpiozero import 

make use of the GPIO Zero MotionSensor, Buzzer 

ibrary's wait for no. import time 

motion function to wait 

for the PIR to sense no pir - MotionSensor(4) 

motion. This gives you bz - Buzzer(3) 

time to leave the area, so 

that it doesn't immediately print("Waiting for PIR to settle") 
sense your presence and pir.wait for no motion() 

raise the alarm when you 

run the code! Once the PIR while True: 

has sensed no motion in its print("Ready") 

field of view, it will print pir.wait for. motion() 
‘Ready’ on the screen and the print("Motion detected!") 
motion detection loop can bz.beep(0.5, 0.25, 8) 
then commence. time.sleep(3) 


>STEP-05 

Motion detection loop 

Usingwhile True: means this is an infinite loop that willrun 
continually, until you stop the program by clicking the ‘X’ icon of its 
window or pressing CTRL*C on the keyboard. Whenever motion is 
detected by the PIR sensor, we get the buzzer to beep repeatedly eight 
times: 0.5 seconds on, 0.25 seconds off, but you can alter the timings. 
We then use time.sleep(3) to wait 3 seconds before restarting the loop. 


>STEP-06 

Adjust the sensitivity 

If you find that the alarm is going off too easily or not at all, you 

may need to adjust the sensitivity of the PIR sensor. This is achieved 
by using a small screwdriver to adjust the plastic screw of the left 
potentiometer, labelled Sx; turn it anticlockwise to increase sensitivity. 
The other potentiometer, Tx, alters the length of time the signal is sent 
after detection; we found it best to turn it fully anticlockwise, for the 
shortest delay of 1 second. 


>PYTHON 3 


DOWNLOAD: 
magpi.cc/2bhwrWQ 
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Link together an ultrasonic distance 
sensor and seven-segment display 
to measure distances 
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Ultrasonic distance 
sensor: gives out a 
pulse proportional to 
any reflecting object 
in front of it 


HC-SRO4 
ultrasonic 
distance sensor 
magpi.cc/ 
1YnqNCZ 


Broadcom 5082- 
7650 7-segment 
display 
magpi.cc/ 
ıYnqQPL 


9x resistors 
(7x 2200, 

1X 5120, 1x КО) 
magpi.cc/ 
1YnqUar 


© «озо» же. ж“ ee 79 sosoo seest * 


he HC-SRo4 ultrasonic distance sensor is a great favourite 
You can use 


any seven- with Pi robot-makers. It works by bouncing ultrasonic sound 
segmen off an object and timing how long it takes for the echo to 
display, but 


alternatives return. This time is then converted into a distance which can be 

might have a з i eroe = ‚ 

different pinot displayed on a single digit, seven segment display. Here you can 
acquire the skills to handle inputs and outputs. You also get to use 
seven-segment displays, which are quite cool in a retro kind of way. 


>STEP-01 

Lighting the display 

The seven-segment display is a collection of LEDs, with one LED 
corresponding to one of the segments. All the anodes (positive ends) 
are connected together; this should be connected to the 3V3 supply. 
The cathodes (negative ends) should be connected to a resistor to limit 
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IC04 


HC-SR04 


Raspberry Pi 3 
Model 8 v1.2 


the LED current, and the other end of the resistor to a GPIO pin. To turn 
the LED on, all you have to do is set the GPIO output to be LOW (OV) 
and it will complete the circuit for the current to flow. 


>STEP-02 

Generating a seven-segment pattern 

The display consists of four bars or segments that can be lit. By choosing 
the segments to light up, you can display a number from 0 to 15, although 
you have to resort to letters (also known as hexadecimal numbers) for 
this. There are, in fact, 128 different patterns you can make, but most 

are meaningless. In our code (ch7listing1.py overleaf), a list called seg 
defines what pins are connected to what segments, and another list called 
segmentPattern defines the LED pattern for each number. 


>STEP-03 

Displaying numbers 

The display function sets up the segments to display any single-digit 
number passed to it. First, it sets all the segments to off, and then if the 
number is less than 16, it goes through the entries in the segmentPattern 
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list for that number and turns on the appropriate segments. Note 
that we can still use on and off even though they're not powered by 
individual GPIO pins, because the LEDs were declared to GPIO Zero 
asactive high - False. 


>STEP-04 

The distance sensor 
The НС-5Код distance sensor signals its reading by producing an output 
pulse that the Pi tries to measure. The GPIO Zero library measures this 
pulse and converts it into a distance by returning a floating-point number 
that maxes out at 1 metre. We then multiply this number by 10 to give 
decimetres. Next, we convert it to an integer to get rid of the fractional 
part of the measurement, so we can show it on our single-digit display. 


>STEP-05 

Building the project 

For our build, we used a dinky little breadboard shield from Dtronixs. 

This allowed for amuch more compact arrangement than aconventional 
breadboard, although you can of course still use one. As the HC-SRo4 uses 
a 5V power supply, the pulse we have to measure is also nominally 5V. 
Therefore, this has to be cut down to 3V3 by using a 5120 and 1КО resistor 
voltage divider. 


>STEP-06 

Using the sensor 

The distance to the reflective object 
is updated every 0.8 seconds. If this 
is greater than a metre, then the 
display will be blank. A display of 

o indicates that the object is less 
than 10cm away. Don't touch the 
sensor, otherwise its readings will 
be wrong. Also, as it has quite a 
wide beam, you can get reflections 
from the side. If several objects 

are in the field of view, then 

the distance to the closest one 

is returned. 


Below 


langu94° 


ché listingl py >PYTHON 3 


DOWNLOAD: 
magpi.cc/2aNx9yf 


# displays the distance in decimetres on a 7-segment display 
from gpiozero import LED 

from gpiozero import DistanceSensor 

import time 


seg = [LED(27,active high-False),LED(25,active high-False),LED(24,active high-False), 
LED(23,active high-False),LED(22,active high-False),LED(18,active high-False), 
LED(17,active high-False)] 


segmentPattern = [[0,1,2,3,4,5], [1,2], [0, 1,6,4,3], [0,1,2,3,61,[1,2,5,6],[0,2,3,5,6], #0 to 5 
[0,2,3,4,5,6], [0,1, 2], [0,1,2,3,4,5,6], [0,1,2,5,6], [0,1,2,4,5,6], #6 to A 
[2,3,4,5,6], [0,3,4,5], [1,2,3,4,6], [0,3,4,5,6], [0,4,5,6] ] #B to F 


sensor - DistanceSensor(15,4) 


def main() : 
print("Display distance on a 7-seg display") 


while 1: 
distance = sensor.distance * 10 # distance in decimeters 
print("distance",distance) 
if distance »- 10.0: 
distance - 16.0 
display(int(distance)) 
time.sleep(0.8) 


def display(number): 
for i in range(0,7): 
seg[i].off() 
if number < 16: 
for i in range(0,len(segmentPattern[number])): 
seg[segmentPattern[number][i]].on() 


it Main program logic: 


if name == ' main ': 
main() 
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mE— he Raspberry Pi can easily detect a digital input via its GPIO 
pins: any input that's approximately below 1.8V is considered 
off, and anything above 1.8V is considered on. An analogue 
input can have a range of voltages from oV up to 3.3V, however, and the 
Raspberry Pi is unable to detect exactly what that voltage is. One way of 
getting around this is by using a capacitor and timing how long it takes 
to charge up above 1.8V. By placing a capacitor in series with a light- 

. dependent resistor (LDR), the capacitor will charge at different speeds 
valute depending on whether it's light or dark. We can use this to create a 
resistor (LDR) laser tripwire! 


GPIO Zero 


1x solderless 
breadboard 


1x ıuF capacitor 


1x laser pointer 


Connect the LDR 
x spp An LDR (also known as a photocell) is a special type of electrical 
emale jumper i А . А i 
wires resistor whose resistance is very high when it’s dark, but reduced 
B TOES when light is shining on it. With the Raspberry Pi turned off, place 
T -to- 
female jumper your LDR into the breadboard, then add the capacitor. It's essential to 
wires (optional) 
Md The LDR is connected to a The light-dependent resistor 

1х drinking straw capacitor: the time taken to (LDR) has lower resistance 

charge this can be measured when light is shining on its head 


1x plastic box 


..... ..... eevee 
e... ..... ..... 


..... 
..... 
““ ж.“ э э э ө э э э ө э ө э ө э э ө э ө э ө э э 


eevee 
..... 
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get the correct polarity for the latter component: its longer (positive) 
leg should be in the same breadboard column as one leg of the LDR. 
Now connect this column (with a leg of both components) to GPIO 4. 
Connect the other leg of the LDR to a 3V3 pin, and the other leg of the 
capacitor to a GND pin. Your circuit should now resemble the diagram 
on page 48. 


Test the LDR 

On the Pi, open IDLE from the Main Menu: Menu > Programming > 
Python 3 (IDLE). Create a new file by clicking File » New File, enter the 
code from ch8listing1.py (page 52), then save it. At the start, we import 
the LightSensor class from GPIO Zero. We then assign the variable 
ldr to the LDR input on the GPIO 4 pin. Finally, we use a never-ending 
while True: loop to continually display the current value of the light 
sensed by the LDR, which ranges from o to 1. Try running the code and 
then shining your laser pointer on it to vary the light level. 
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Shining the laser 
onto the LDR in a 
darkened room will 
dramatically affect 
the measured 

light Level 


49 


MägPi 
ESSENTIALS 


A simple piezo 
buzzer is made to ^s 
beep whenever the $5 
laser tripwire beam .. 
5% 


is broken 


By timing how long it fə» 
takes to charge the .. 
capacitor, we сап >> 
work out the light > 
levelon the LDR 


The light-dependent 
resistor (LDR) has 
lower resistance © 
when the laser is 5% 
shining onto it .. 
> 


>STEP-03 

Enclose the LDR 

Unless you're working in a darkened room, you'll probably notice little 
difference between the measured light level when the laser pointer is 
directed onto the LDR and when it's not. This can be fixed by reducing 
the amount of light that the LDR receives from other light sources in 
the room, which will be essential for our laser tripwire device to work 
effectively. We'll achieve this by cutting off a short section - between 
2cm and 5cm - of an opaque drinking straw, and inserting the head 

of the LDR into one end. Now try the test code again and see how the 
measured light level changes when you shine the laser pointer into the 
other end of the straw. You should notice a larger difference in values. 


>STEP-04 
| Wire up the buzzer 

To create an audible alarm for our laser tripwire, we’ll add a piezo 
buzzer to the circuit. Again, the polarity has to be correct: connect the 
column of the buzzer's longer leg to GPIO 17, and the shorter leg to a 
GND pin. Let's test it's working. In IDLE, create a new file, enter the 
code from ch8listing2.py (page 52), and save it. At the top, we import 
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the Buzzer class from GPIO Zero. Next, we assign the buzzer 
variable to the buzzer output on GPIO 17. Finally, we use buzzer.beep 
to make the buzzer turn on and off repeatedly at the default length 
of 1 second. To stop it, close the Python shell window when it's off. 


>STEP-05 

Test the tripwire 

We'll now put everything together so that the laser pointer shines at the 
LDR (through the straw) and whenever the beam is broken, the buzzer 
sounds the alarm. In IDLE, create a new file, enter the code from 
ch8listing 3.py (page 52), and save it. At the start, we import the Buzzer 
and LightSensor classes from GPIO Zero. We also import the sleep 
function from time; we'll need this to slow the script down a little to give 
the capacitor time to charge. As before, we assign variables for the buzzer 
and LDR to the respective devices on GPIO pins 4 and 17. We then use a 
while True: loop to continually check the light level on the LDR; if it falls 
below 0.5, we make the buzzer beep. You can change this number to adjust 
the sensitivity; a higher value will make it more sensitive. Try running the 
code; if you break the laser beam, the buzzer should beep for 8 seconds. You 
can adjust this by altering the buzzer . beep parameters and sleep time. 


>STEP-06 


Package it up Below 
"m А A Place your laser 
Once everything is working well, you can enclose your Raspberry Pi реле жоса 
and breadboard in a plastic box (such as an old ice cream tub), with the doorway; when 
P А А А someone breaks 
drinking straw poking through a hole in the side. If you prefer, you can thebeam, the 


remove the breadboard and instead connect the circuit up directly by alarm will sound 
poking the legs of the components 
into female-to-female jumper 
wires, with the long capacitor leg 
and an LDR leg together in one 
wire end, connected to the relevant 
pins. Either way, place the tub near 
a doorway with the laser pointer 
on the other side, with its beam 
shining into the straw. Run your 
code and try walking through the 
doorway: the alarm should go off! 
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>PYTHON 3 


chóliatingl.py DOWNLOAD: 


magpi.cc/2bhxwxC 


from gpiozero import LightSensor 
ldr = LightSensor(4) 


while True: 
print(ldr.value) 


chölisting2.py 


from gpiozero import Buzzer 


buzzer = Buzzer(17) 
buzzer.beep() 


chölistingd.py 


from gpiozero import LightSensor, Buzzer 
from time import sleep 


ldr = LightSensor (4) 
buzzer = Buzzer(17) 


while True: 

sleep(0.1) 

if ldr.value « 0.5: 
buzzer.beep(0.5, 0.5, 8) 
sleep(8) 

else: 
buzzer.off() 
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nother way for the Raspberry Pi to detect analogue inputs is 

by using an analogue-to-digital converter (ADC) chip, such as 
the MCP3008. The latter offers eight input channels to connect 
sensors and other analogue inputs. In this tutorial, we'll hook up a 


GPIO Zero potentiometer to an MCP3008, to control the brightness of an LED by 
turning the knob. We'll then add a second potentiometer and create an 

1x solderless | j . . | : 

breadboard internet radio, using the two potentiometers to switch the station and 


alter the volume. 


a >STEP-01 
potentiometers Enable SPI 

1x LED The analogue values from the ADC chip will be communicated to the Pi 
using the SPI protocol. While this will work in GPIO Zero out of the box, 
you may get better results if you enable full SPI support. To do this, 
open a terminal window and enter: 


1x MCP3008 
ADC chip 


1x 3302 resistor 


7x male-to- 
female jumper 
wires 


sudo apt-get install python3-spidev python-spidev 


10x male-to-male 
jumper wires 


Click OK and reboot the Pi. 


Four legs are 
connected to 


Ld LJ . .. 
special GPIO pins, |* * . . б .. 
while the rest 4 2 » > < >? 
arehookedupto >> d E rs 2 
the power and .. e Ё e 39% 
ground rails 4A . . б .. 

. . . .. 

LJ LJ Ld .. 
The MCP3008 е - » на 
ADC chip 
straddles the CAMERA) 
central groove; 


the side shown 
without wires 
comprises eight 
input channels 


PODEd IW 


. 
LI 
"е 9|» * * * * * * * * 


“. ее ее е“ “е . . 
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>STEP-02 

Connect the ADC 

As usual, it’s best practice to turn off the Pi while creating our circuit. 
As you can see from the diagram, there’s quite a lot of wiring required 
to connect the MCP3008 ADC to the Pi’s GPIO pins. As an alternative, 
you could use an Analog Zero (magpi.cc/2aey1b6), which provides the 
MCP3008 chip on a handy add-on board. 

First, place the MCP3008 in the middle of the breadboard, 
straddling its central groove. Now connect the jumper wires asin 
the diagram. Two go to the ‘+’ power rail, connected to a 3V3 pin; 
two others are connected to a GND pin via the “— rail. The four 
middle legs of the ADC are connected to GPIO pins 8 (CEO), 10 (MOSI), 
9 (MISO), and 11 (SCLK). 


>STEP-03 

Read the value 

Now the ADC is connected to the Pi, you can wire devices up to its eight 
input channels (numbered o to 7). Here, we'll connect a potentiometer, 
which is a variable resistor: as you turn its rotary knob, the Pi reads the 
voltage (from oV to 3.3V). We can use this for precision control of other 


ESSENTIALS 


>STEP-05 
Light an LED 


components, such as an LED. As in 
the diagram, connect one outer leg 
of the potentiometer (top-right) 
to the ‘-’ ground rail, the other 
side to the ‘+’ power rail, and the 
middle leg to the first input of the 
MCP3008: channel 0. 


>STEP-04 

Read the value 

We can now read the 
potentiometer's value in 
Python. On the Pi, open IDLE 
from the Main Menu: Menu » 
Programming » Python 3 (IDLE). 
Create a new file by clicking File 
» New file, then enter the code 
from chglisting1.py (page 59), 
and save it. At the top we import 
the MCP3008 class from GPIO 
Zero, then assign the pot variable 
to the ADC's channel 0. A while 
True: loop then continuously 
displays the potentiometer's 
value (from 0 to 1) on the screen; 
try turning it as the code runs, 

to see the number alter. 


Next, we'll add an LED to the circuit as in the diagram, connecting 
its longer (positive) leg to GPIO 21, and its shorter leg via a resistor 


to the <>” ground rail. In Ір 


E, create a new file, enter the code from 


cholisting2.py (page 59), and save it. At the start, we import the 
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MCP3008 and PWMLED classes. The latter enables us to control the 
brightness of an LED using pulse-width modulation (PWM). We create 
a PWMLED object on GPIO 21, assigning it to the led variable. We assign 
our potentiometer to channel 0, as before. Finally, we use GPIO Zero’s 
clever source and values system to pair the potentiometer with the 
LED, to continuously set the latter's brightness level to the former's 
value. Run the code and turn the knob to adjust the LED's brightness. 


Add a second pot 

Let's add a second potentiometer to our circuit as in the diagram, 
with its middle leg connected to channel 1 of the MCP3008. We'll now 
use both potentiometers to control our LED's blink rate. In IDLE, create 
a new file, enter the code from chglisting3.py (page 59), and save it. 
Here, we create two separate pot1 and pot2 variables, assigned to the 
ADC's channels 0 and 1 respectively. In awhile True: loop, we then 
print the two values on the screen and make the LED blink, with its on 
and off times affected by our two potentiometers. Run the code and 
twist both knobs to see how it changes. 


Some serious 


spaghetti wiring 

is required; 
alternatively, 

you could use an 
Analog Zero board 
to reduce this 
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>STEP-07 

Install mplayer 

We'll use the same circuit to create a simple internet radio, with one 
potentiometer used to switch the station and the other to adjust the 
volume. First, we'll need to install the MPlayer media player to be able 
to play M3U internet radio streams, since Omxplayer can't do this. 
Open a terminal window and enter: 


sudo apt-get install mplayer 


>STEP-08 

Make the radio 

Open IDLE, create a new file, enter the code from chglisting4.py (page 
60), and save it. At the start, we import the MCP3088 class, along with 
the time and os libraries; the latter will enable us to start MPlayer by 
sending commands directly to the terminal. We create variables for 
the station and volume dials, on ADC channels o and 1 respectively. 
We then assign variables to two radio stream URLs, for Magic and BBC 
Radio 1, and assign the current, station variable to the latter. 

Next, we create a function called change station which includes 
an if condition, so it only triggers when the station set by the first 
potentiometer position is different from the currently selected one 
(current station). If so, it stops the current stream and starts 
playing the new one, before reassigning the current station 
variable to it. 

Finally, in awhile True: loop, we set the audio volume to the 
value of the second potentiometer using amixer; we've assigned 
a minimum value of 6596, but you can alter this. It then checks 
whether the first potentiometer is below or above 0.5 and calls the 
change station function. 

Run the code and try turning both potentiometers to switch the 
station and adjust the volume. To keep things simple, we've only 
used two radio stations in this example, but you could easily add more. 
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qanguage 


>PYTHON 3 


ch9listing! py DOWNLOAD: 


magpi.cc/2aNxLUM 
from gpiozero import MCP3008 


pot = MCP3008(channel-0) 


while True: 
print(pot.value) 


ch9listing2.py 


from gpiozero import MCP3008, PWMLED 


pot 
led 


MCP3008(0) 
PWMLED(21) 


led.source = pot.values 


ch9listing3.py 


from gpiozero import MCP3008, PWMLED 


poti = MCP3008(0) 
pot2 - MCP3008(1) 
led - PWMLED(21) 


while True: 
print(pot1.value, pot2.value) 
led.blink(on time=pot1.value, off time=pot2.value, n-1, background-False) 
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cholisting!l.py 


from gpiozero import MCP3008 
import time 
import os 


station dial - MCP3008(0) 
volume dial - MCP3008(1) 


Magic = "http://tx.whatson.com/icecast.php?i-magic1054.mp3.m3u" 
Radiol = “http://www. listenlive.eu/bbcradio1.m3u" 


current station = Radiol 


def change station(station): 
global current station 
if station !- current station: 
os.system("killall mplayer") 
os.system("mplayer -playlist 
current station - station 


+ station + " &") 


while True: 
vol = (65 + volume dial.value * 35) 
os.system("amixer set PCM -- " + str(vol) +"%") 


if station dial.value »- 0.5: 
station - Magic 
change station(station) 
elif station dial.value « 0.5: 
station = Radio1 
change station(station) 
time.sleep(0.1) 
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GPIO Zero 


1x solderless 
breadboard 


1x MCP3008 
ADC chip 


1x TMP36 
temperature 
sensor 


5x LEDs (red, 
yellow, green) 


5x 330Q resistor 
1x 1UF capacitor 


11x male-to- 
female jumper 
wires 


8x male-to-male 
jumper wires 


The TMP36 
temperature 
sensor (bottom- 
right) is connected 
to an input 
channel of the 
MCP3008 chip 


ontinuing the theme of analogue inputs, we 


"ll use the 


MCP3008 analogue-to-digital converter (ADC) again and this 
time hook it up to a temperature sensor. We'll display the 


ED’s and use GPIO 


current temperature on the screen, then add some L! 
Zero's handy LEDBarGraph class to get them to light 
the temperature. 


Enable SPI 


up according to 


As in chapter 9, the analogue values from the ADC chip will be 


communicated to the Pi using the SPI protocol. While this will work in GPIO 
Zero out of the box, you may get better results if you enable full SPI support. 
If you haven't done this already, open a terminal window and enter: 


sudo apt-get install python3-spidev python-spidev 


Click OK and reboot the Pi. 
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>STEP-02 
Connect the ADC 
If you already have the MCP3008 wired up from chapter 9, leave itin 
place, straddling the central groove of the breadboard. As noted before, 
there’s quite a lot of wiring required; as an alternative, you could use 
an Analog Zero (magpi.cc/2aey1b6) add-on board to cut down on this. 
Otherwise, connect the jumper wires as in the diagram. Two go to the 
‘+’ power rail, connected to a 3V3 pin; two others are connected to a 
GND pin via the <>” rail. The four middle legs of the ADC are connected 
to GPIO pins 8 (CEo), 10 (MOST), 9 (MISO), and 11 (SCLK). 


>STEP-03 

Add the sensor 

Now that the ADC is connected to the Pi, you can wire devices up to its 
eight input channels, numbered o to 7. Here, we'll connect a TMP36 


CE E 


CAMERA) 


Magi 
ESSENTIALS 


analogue temperature sensor. It's vital that this is wired up correctly, 
otherwise it'll overheat. With its flat face towards you, the left-hand 
leg is for power, so connect this to the “+ power rail. The right-hand 
leg is connected to the ‘-’ ground rail. Its middle leg is the output; 
here we're connecting to channel 7 (the nearest one) of the MCP3008. 


Finally, to help stabilise the readings which might otherwise be erratic, 
we'll add a capacitor to link its output and ground legs. 


>STEP-04 

Take the temperature 

We can now read the sensor’s value in Python. On the Pi, open IDLE 
from the Main Menu: Menu > Programming > Python 3 (IDLE). Create 
a new file, enter the code from ch1olisting1.py (page 66), and save 

it. At the top we import the MCP3@@8 class from GPIO Zero, then the 
sleep function from the time library. Next, we define a function that 


Each LED's shorter leg is We use five LEDs to display 
connected to the ground a bar graph relating to the 

rail via a resistor, to limit temperature; each LED is 

the current connected to a different GPIO pin 


- 
- 


(CAMERA) 


À 
à 
| 


| 
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converts the sensor reading into degrees Celsius. We then assign the 
When we run the 


adc variable to channel 7 of the MCP3008. Finally, we use a for loop final code, the LEDs 

to display the converted temperature on the screen, updating it every АН up to 22” 
Р х " E А e temperature 

second. Note: if you've just been handling the sensor, it might take a read bythe sensor 


little while to settle down. 


LED bar graph 

Next, we'll add our line of five LEDs to the circuit, as in the diagram. 

From green to red, we've connected their longer legs to the following 

GPIO pins: 26, 19, 13, 6, and 5. In IDLE, create a new file, enter the 

code from ch10listing2.py (page 67), and save it. At the start, we 

import the LEDBarGraph class from GPIO Zero; this will enable us to 

use the LEDs to display a bar graph, saving a lot of complex coding. 

We assign the graph variable to our LEDs on the GPIO pins mentioned | 
previously, and also enable PWM so that we can adjust their 


brightness for a more accurate display. We then set graph.value І = 


to various fractions between o and 1 to light the relevant number of 
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LEDs from green to red, including partially lit ones for precision. Note 
that if the value is negative, it will light the LEDs from the other end, 
red ones first. 


>STEP-06 

Display the temperature 

So, we've got our temperature sensor and LED bar graph set up; let's 
combine them to display the temperature on the LED bar graph. In 
IDLE, create a new file, enter the code from ch10listing 3.py, and 

save it. At the top, we import GPIO Zero's MCP3008 and LEDBarGraph 
classes, along with the sleep function from the time library. As in our 
original code, we then define a function to convert the temperature 
sensor's readings to degrees Celsius. We assign the adc variable to 
channel 7 of the MCP3008 and graph to our LEDs’ GPIO pins, setting 
PWM to true. Finally, in our for loop, we add a bars variable to 
determine how many LEDs are lit in the bar graph. In this example, 
we've divided temp by 35, which is around the maximum temperature 
for the UK, so if it gets to 35°C, all the LEDs should light up fully. 
Naturally, you can adjust this number to suit your own location's 
climate. When ready, run the code and see those LEDs light up to 
show the current temperature. 


chlOlistingl.py 


from gpiozero import MCP3008 
from time import sleep 


def convert_temp(gen): 
for value in gen: 
yield (value * 3.3 - 0.5) * 100 


adc = MCP3888(channel=7) 
for temp in convert_temp(adc.values): 


print("The temperature is", temp, "C") 
sleep(1) 
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chlOlisting2.py 


from gpiozero import LEDBarGraph 
from time import sleep 


graph = LEDBarGraph (26, 19, 13, 6, 5, pwm=True) 


graph.value 
sleep(1) 
graph.value 
sleep(1) 
graph.value 
sleep(1) 
graph.value 
sleep(1) 
graph.value 
sleep(1) 
graph.value 


qanguage 


>PYTHON 3 


DOWNLOAD: 
magpi.cc/2bhw@bJ 


1/10 


3/10 


-3/10 


9/10 


95/100 


chlOlistingd.py 


from gpiozero import MCP3008, LEDBarGraph 
from time import sleep 


def convert_temp(gen): 
for value in gen: 
yield (value * 3.3 - 0.5) * 100 


adc - MCP3008(channel-7) 
graph - LEDBarGraph (26, 19, 13, 6, 5, pwm-True) 


for temp in convert temp(adc.values): 
bars - temp / 35 


graph.value - bars 


sleep(1) 
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GPIO Zero 


1x 3D-printed 
KOROBOT shell 
and wheels, 

or some craft 
materials 
magpi.cc/ 
1PCfwMK 


1xHC-SRO4 
ultrasonic 
sensor 
magpi.cc/ 
1PCfAMs 


2x 28BYJ-48 
stepper motors 
& ULN2003A 
driver boards 
magpi.cc/ 
ıPCfCE3 


1x half-size 
solderless 
breadboard 


Mobile power 
bank 


Various jumper 
wires 


2x DC motors 
and wheels 
(optional for 
steps 1-3) 


Used to detect obstacles, the 
HC-SRo4 ultrasonic sensor is 
connected via a mini breadboard 


е е 


Each stepper motor is wired to a driver 
board which is then connected to four 
GPIO pins on the Pi 


aspberry Pi robotics is a popular pastime, but has previously 
required some complex coding to steer your bots. Fortunately, 
GPIO Zero makes it much simpler with its Motor and Robot 
classes. We have a play around with these at the start of our guide 
to control a couple of DC motors, before showing you how to build 
and program a two-wheeled ZeroBot using a Pi Zero and two stepper 
motors for precision control. 


Connect DC motors 

To enable the Raspberry Pi to control DC motors, an H-bridge motor 
driver board is required; you should never connect motors directly 
to the Pi, as this is likely to damage the latter. There are numerous 
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GPIO Zero's 

Robot class makes 
it very easy to 
control a two- 
wheeled robot like 
this one 


motor drivers available; for steps 1-3 of this guide, we're using the one 
supplied in the popular CamJam EduKit #3 (magpi.cc/2algEVU), which 
fits onto the Pi's GPIO header. Each motor is connected by two wires 
going to positive and negative terminals on the driver board, which is 


hooked u 


p to a power supply such as a battery box or a 5V pin on the 


Pi. Either way, the Raspberry Pi itself is normally powered separately, 
using a mobile power bank if you want to use your robot untethered. 


Runam 


otor 


GPIO Zero includes a Motor class for running bidirectional motors 
connected via an H-bridge motor driver circuit. On the Raspberry Pi, 


open IDLI 


E from the Main Menu: Menu > Programming > Python 3 


(IDLE). Create a new file by clicking File » New file, then enter the 
code from ch11listing1.py (page 73). At the top, we import the Motor 
class from GPIO Zero, along with sleep from time. We then assign the 
motor variable to the Motor class on the two GPIO pins connected to 
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our motor: in this example, 8 and 7. When we use motor. forward(), 
the motor should run forwards. Within the brackets, we can add a 
speed between о and 1 (the default). Similarly, motor.backward 

will run it backwards, while motor.stop will stop the motor if it's 
still running. 


>STEP-03 
Move a robot 
While you can control your motors individually using the Motor class, 
GPIO Zero also includes the Robot class for controlling a two-wheeled 
robot. Assuming you have such a robot already assembled, open IDLE, 
create a new file, enter the code from chiilisting2.py (page 74), and 
save it. At the top, we import the Robot class from GPIO Zero, along 
with sleep from the time library. We then assign the robot variable 
to it, with the relevant GPIO pins for the left and right motors. We can 
then run various commands to control it, including telling it to spin 
left or right. In this example, we're using a for loop with forward and 
turn right directions to make it drive around in a square pattern; adjust 
the time.sleep values to determine the square size. Try altering the 
directions to make different patterns. 

Note: To save plugging your robot's Pi into a display each time, you 
can SSH into it to control it from another computer, or even a tablet 
or smartphone, connected to the same wireless network. 


>STEP-04 
Build a ZeroBot 
Next, we'll show you how to build a ZeroBot based on a Pi Zero and two 
stepper motors. The 28BYJ-48 is a cheap but versatile stepper motor 
that can normally be bought with a ULN2003A driver board for under 
£4. Stepper motors can be programmed to move in discrete steps, 
rather than just turned on/off like servos. Using the Pi Zero, you'll be 
able to control the speed and positioning of the motors very accurately. 
To cause the motor to rotate, you provide a sequence of ‘high’ and ‘low’ 
evels to each of the four inputs. The direction can then be reversed by 
reversing the sequence. In the case of the 28BYJ-48, there are four- | Ei 
step and eight-step seguences. The four-step is faster, but the torgue 


is lower. The example code іп ch11listing3.py (page 74) lets you specify | {| | = 
the number of steps through the seqsize variable. 
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Each motor has a connector block at the end of its coloured wires that 
slots into the white header on the ULN2003A. The GPIO pins controlling 


that motor connect to the four input pins below the IC, while the 5V power 


=] | | and ground connections go to the bottom two pins on the right. 


>STEP-05 


Eyes to see 

We'll give our 
obstacles, cou 
pins, includin 


ZeroBot some simple “eyes” that allow it to detect 
rtesy of the HC-SRo4 ultrasonic sensor. This has four 
g ground (GND) and 5V supply (VCC). Using Python, 


you can tell the Pi to send an input signal to the Trigger Pulse Input 


(TRIG) by setti 


ng a GPIO pin's output to HIGH. This will cause the 


sensor to send out an ultrasonic pulse to bounce off nearby objects. 


Above The sensor de 
The diminutive 
ZeroBot features 


tects these reflections, measures the time between the 


trigger and returned pulse, and then sets a 5V signal on the Echo Pulse 


аРі 2его, two Output (ECHO) pin. Python code can measure the time between output 


stepper motors, 
and a 3D-printed and return pu 


chassis (page 69). Its] 


ses. Connect the HC-SRo4 as shown in the diagram 
ECHO output is rated at 5V, which could damage the 
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Pi. To reduce this to 3V, use two resistors to create a simple voltage 
divider circuit, as shown in the diagram. 

Once you have all your components connected, you can test the code 
on a bench before building the full robot. Point the ‘eyes’ away from you 
and run the code. The red LEDs on the ULN2003As should flash and both 
motors should start turning. Our example has the bot move in a square. 
Check that the motors behave accordingly then rerun the code, but this 
time place your hand a couple of centimetres in front of the HC-SRo4 
and check that everything stops. 


>STEP-06 
Give it a body 
Now it’s time to give the bot a body. If you have access to a 3D printer, 
you can print the parts for the ZeroBot. This design fits together 
easily, although you do need to glue the chassis end-caps in place. 
Alternatively, you could construct a similar design using reasonably 
thick cardboard for the wheels and part of a plastic bottle as the main 
tubular chassis. Use more cardboard for the end-caps. 

Put your mobile power bank at the bottom of the chassis tube, 
then attach the motors to the end-caps with screws. Next, place 
the ULN2003A boards on top of the power bank, and then sit the 
breadboard with the HC-SRo4 ‘eyes’ on top. Finally, slot the Pi Zero 
in at the back. АП nice and cosy, and ready to roll! 


chillistingl.py 


from gpiozero import Motor 
from time import sleep 


motor = Motor(forward=8, backward=7) 

while True: 
motor.forward() | [| ШЕН 
sleep(5) 
motor.backward() 


d Ir 
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chillisting2.py 
І 


from gpiozero import Robot 
from time import sleep 


=] | robot = Robot(left-(8, 7), right-(10, 9)) 


for i in range(4): 
robot .forward() 
sleep(1) 
robot.right() 
sleep(0.2) 


chlllisting3.py 


import time, sys 
from gpiozero import DistanceSensor, OutputDevice 
from threading import Thread 


sensor = DistanceSensor(echo = 16, trigger = 20) 


IN1 m1 = OutputDevice(17) 

IN2 m1 = OutputDevice(18) 

IN3 m1 = OutputDevice(21) 

IN4 m1 = OutputDevice(22) 

StepPins m1 = [IN1 m1,IN2 m1,IN3 т1,ІМ4 m1] # Motor 1 pins 
IN4 m2 = OutputDevice(19) 

IN3 m2 - OutputDevice(13) 

IN2 m2 - OutputDevice(5) 

IN1 m2 - OutputDevice(6) 

StepPins m2 = [IN1 m2,IN2 m2,IN3 m2,IN4 m2] # Motor 2 pins 
Seq = [[1,0,0,1], # Define step sequence 

[1,0,0,0], 4 as shown in manufacturer?s datasheet 
[15105915 
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StepCount - len(Seq) Tanguage 


all clear - True >PYTHON 3 
running = True 
DOWNLOAD: 
def bump_watch(): # thread to watch for obstacles magpi.cc/2bhwBxf 
global all clear 
while running: 
value - sensor.distance 
if value « 0.1: # trigger if obstacle within 10cm 
all clear - False 
else: 
all clear - True 
def move bump(direction-'F', segsize=1, numsteps-2052): 
counter = 0 # 2052 steps = 1 revolution for step size of 2 
StepDir = seqsize # Set to 1 or 2 for fwd, -1 or -2 for back 
if direction -- 'B': 
StepDir - StepDir * -1 
WaitTime - 10/float(1000) it adjust this to change speed 
StepCounter = ® 
while all_clear and counter < numsteps: # only move if no obstacles 
for pin in range(0, 4): 
Lpin = StepPins m1[pin] 
Rpin - StepPins m2[pin] 
if Seq[StepCounter][pin]!=0: t F=fwd, B=back, L=left, R=right 
if direction == 'L' or direction == 'B' or direction == 'F': 
Lpin.on() # Left wheel only 
if direction == 'R' or direction == 'B' or direction == 'F': 
Rpin.on() # Right wheel only 
else: 
Lpin.off() 
Rpin.off() 
StepCounter += StepDir 
if (StepCounter>=StepCount): # Repeat sequence 
StepCounter = ® 
if (StepCounter<8): 
StepCounter = StepCount+StepDir 
time.sleep(WaitTime) # pause 
counter+=1 
t1 = Thread(target-bump watch) # run as separate thread | Е ШЕ 
t1.start() # start bump watch thread 
for i in range(4): # Draw a right-handed square 


move bump( F',-2,4104) 
move bump( R',-2,2052) 


running - False 
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To help you get started with GPIO Zero, here's a handy reference guide to 


its many useful classes that make Python coding for physical computing 


so much simpler 
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[ GPIO PIN 
NUMBERS 1 


Note that all GPIO 


pin references 
in this guide use 
ш Broadcom (BCM) 


numbering. Refer 
to pinout.xyz for 
more details. 


GPIO Zero includes a range of classes that make it easy to control output components 


such as LEDs, buzzers, and motors... 


LED 


gpiozero.LED(pin, active high-True, initial value-False) 


Use this class to turn an LED on and off. The LED should have its longer 
leg (anode) connected to a GPIO pin, and the other leg connected via 

a limiting resistor to GND. The following example will light an LED 
connected to GPIO 17: 


from gpiozero import LED 
led - LED(17) 
led.on() 


Methods: 


on() 


Turn the device on. 


off() 
Turn the device off. 


blink(on time-1, off time-1, nzNone, background-True) 
Make the device turn on and off repeatedly. 
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toggle() 

Reverse the state of the device; if on, it'll turn off, and vice versa. 
is lit 

Returns True if the device is currently active, and False otherwise. 
pin 

The GPIO pin that the device is connected to. 


PWMLED 


gpiozero.PWMLED(pin, active high=True, 
initial value-0, frequency-100) 


This class is used to light an LED with variable brightness. As before, a 
resistor should be used to limit the current in the circuit. The following 
example will light an LED connected to pin 17 at half brightness: 


from gpiozero import PWMLED 


led - PWMLED(17) 
led.value - 0.5 


Methods: 


on() 


Turn the device on. 


off() 
Turn the device off. 


blink(on time-1, off time-1, fade in time-0, 
fade out time-0, n=None, background-True) 
Make the device turn on and off repeatedly. 
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pulse(fade in time=1, fade out time=1, 
n=None, background-True) 
Make the device fade in and out repeatedly. 


toggle() 
Toggle the state of the device. If it's currently off (value is 0.0), this 
changes it to ‘fully’ on (value is 1.0). If the device has a duty cycle 
(value) of 0.1, this will toggle it to 0.9, and so on. 

is lit 

Returns True if the device is currently active, and False otherwise. 
pin 

The GPIO pin that the device is connected to. 


value 
The duty cycle of the PWM device, from 0.0 (off) to 1.0 (fully on). 


RGBLED 


gpiozero.RGBLED(red, green, blue, active high-True, 
initial value-(0, ©, Ө), pwm=True) 


As shown in chapter 5, this class is used to light a full-colour LED 
(composed of red, green, and blue LEDs). Connect its longest leg 
(cathode) to GND, and the other to GPIO pins via resistors (or use one 
on the cathode). The following code will make the LED purple: 

from gpiozero import RGBLED 


led - RGBLED(2, 3, 4) 
led.color - (1, 0, 1) 


Methods: 


on() 


Turn the device on: equivalent to setting the LED colour to white (1, 1, 1). 
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off() 
Turn the device off: equivalent to setting the LED colour to black 
(0) ОЛО) 


blink(on time-1, off time-1, fade in time-0, fade - 
out time-0, on со1ог-(1, 1, 1), off color-(0, Ө, Ө), 
n=None, background-True) 

Make the device turn on and off repeatedly. 


pulse(fade in time=1, fade out time-1, on color-(1, 1, 
1), off color-(0, 0, 0), nzNone, background-True) 
Make the device fade in and out repeatedly. 


toggle() 

Toggle the state of the device. If it’s currently off (value is (0, 0, 
0)), this changes it to ‘fully’ on (value is (1, 1, 1)). If the device 
has a specific colour, this method inverts it. 


color 

Represents the color of the LED as an RGB 3-tuple of (red, green, 
blue), where each value is between О and 1 if pwm-True, 

and only 0 or 1 if not. 

For example, purple is (1, 0, 1), yellow is (1, 1, 0), 

and orange is (1, 0.5, 0). 


is lit 
Returns True if the LED is currently active (not black) 
and False otherwise. 


Buzzer 


gpiozero.Buzzer(pin, active high-True, 
initial value-False) 


This class is used to control a piezo buzzer. This example will sound 
a buzzer connected to GPIO pin 3: 
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from gpiozero import Buzzer 
bz - Buzzer(3) 
bz.on() 


Methods: 


on() 


Turn the device on. 


off() 
Turn the device off. 


beep(on time-1, off time-1, n=None, background-True) 
Make the device turn on and off repeatedly. 


toggle() 
Reverse the state of the device; if on, it'll turn off, and vice versa. 


is active 
Returns True if the device is currently active, and False otherwise. 


pin 
The GPIO pin that the device is connected to. 


Motor 


gpiozero.Motor(forward, backward, pwm=True) 


This class will drive a generic motor connected via an H-bridge motor controller. The 
following example will make a motor connected to GPIO pins 17 and 18 turn ‘forwards’: 


from gpiozero import Motor 


motor - Motor(17, 18) 
motor.forward() 
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Methods: 


backward(speed=1) 
Drive the motor backwards. Speed can be any value between 0 and 1 
(if pwm=True). 


forward(speed-1) 
Drive the motor forwards. Speed can be any value between 0 and 1 


(if pwm-True). 


stop() 
Stop the motor. 


02. INPUT DEVICES 


The GPIO Zero module includes a range of classes that make it easy to 
obtain values from input devices such as buttons and sensors... 


Button 


gpiozero.Button(pin, pull up=True, bounce time=None) 


Use this class with a simple push button or switch. The following 
example will print a line of text when a button connected to GPIO 
pin 4 is pressed: 


from gpiozero import Button 
button - Button(4) 


button.wait for press() 
print("The button was pressed!") 
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Methods: 


wait for press(timeout-None) 
Pause the script until the device is activated, or the timeout (in 
seconds) is reached. 


wait for release(timeout-None) 
Pause the script until the device is deactivated, or the timeout 
(in seconds) is reached. 


when pressed 
The function to run when the device changes state from inactive 
to active. 


when released 
The function to run when the device changes state from active 
to inactive. 


when held 
The function to run when the device has remained active for 
hold time seconds. 


hold time 

The length of time (in seconds) to wait after the device is activated, 
until executing the when held handler. If hold repeat is True, 
this is also the length of time between calls to when held. 


hold repeat 
If True, when held will be executed repeatedly with hold time 
seconds between each call. 


held time 
The length of time (in seconds) that the device has been held for. 


is held 


When True, the device has been active for at least 
hold time seconds. 
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is pressed 
Returns True if the device is currently active, and False otherwise. 


pin 
The GPIO pin that the device is connected to. 
pull up 


If True, the device uses a pull up resistor to set the GPIO pin ‘high’ 
by default. 


Line Sensor 


gpiozero.LineSensor(pin) 


This class is used to read a single pin line sensor, like the TCRT5000 
found in the CamJam Edukit #3. The following example will print a line 
of text indicating when the sensor (with its output connected to GPIO 
pin 4) detects a line, or stops detecting one: 


from gpiozero import LineSensor 
from signal import pause 


sensor - LineSensor(4) 

sensor.when line - lambda: print('Line detected') 
sensor.when no line - lambda: print('No line detected') 
pause() 


Methods: 


wait for line(timeout-None) 
Pause the script until the device is deactivated, or the timeout 
(in seconds) is reached. 


wait for no line(timeout-None) 


Pause the script until the device is activated, or the timeout 
(in seconds) is reached. 
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when line 
The function to run when the device changes state from active 
to inactive. 


when no line 
The function to run when the device changes state from inactive 
to active. 


pin 
The GPIO pin that the device's output is connected to. 


Motion Sensor 


gpiozero.MotionSensor(pin, queue len-1, sample rate-10, 
threshold-0.5, partial-False) 


As shown in chapter 6, this class is used with a passive infrared (PIR) 
sensor, such as the one found in the CamJam EduKit #2. The following 
example will print a line of text when motion is detected by the sensor 
(with its middle output leg connected to GPIO pin 4): 


from gpiozero import MotionSensor 


pir - MotionSensor(4) 
pir.wait for motion() 
print("Motion detected!") 


Methods: 

wait for motion(timeout-None) 

Pause the script until the device is activated, or the timeout 
(in seconds) is reached. 

wait for no motion(timeout-None) 


Pause the script until the device is deactivated, or the timeout 
(in seconds) is reached. 
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motion detected 
Returns True if the device is currently active, and False otherwise. 


when motion 
The function to run when the device changes state from inactive 
to active. 


when no motion 
The function to run when the device changes state from active 
to inactive. 


pin 
The GPIO pin that the device's output is connected to. 


Light Sensor 


gpiozero.LightSensor(pin, queue len=5, charge time 
limit-0.01, threshold-0.1, partial-False) 


As shown in chapter 8. Connect one leg of the LDR to the 3V3 pin; 
connect one leg of a 1НЕ capacitor to a ground pin; connect the other 
leg of the LDR and the other leg of the capacitor to the same GPIO pin. 
This class repeatedly discharges the capacitor, then times the duration 
it takes to charge, which will vary according to the light falling on the 
LDR. The following code will print a line of text when light is detected: 


from gpiozero import LightSensor 

ldr - LightSensor(18) 

ldr.wait for light() 

print("Light detected!") 
Methods: 


wait for dark(timeout-None) 
Pause the script until the device is deactivated, or the timeout 
(in seconds) is reached. 
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wait for light(timeout-None) 
Pause the script until the device is activated, or the timeout 
(in seconds) is reached. 


light detected 
Returns True if the device is currently active, and False otherwise. 


when dark 
The function to run when the device changes state from active to inactive. 


when light 
The function to run when the device changes state from inactive to active. 


pin 
The GPIO pin that the device is connected to. 


Distance Sensor 


gpiozero.DistanceSensor(echo, trigger, queue 1еп-30, 
max distance-1, threshold distance-0.3, partial-False) 


As shown in chapter 7, this class is used with a standard HC-SRo4 
ultrasonic distance sensor, as found in the CamJam EdukKit #3. Note: 

to avoid damaging the Pi, you'll need to use a voltage divider on the 
breadboard to reduce the sensor's output (ECHO pin) from 5V to 3.3V. 
The following example will periodically report the distance measured 
by the sensor in cm (with the TRIG pin connected to GPIO17, and ECHO 
pin to GPIO18): 


from gpiozero import DistanceSensor 
from time import sleep 


sensor - DistanceSensor(echo-18, trigger-17) 

while True: 
print('Distance: 
sleep(1) 


» Sensor.distance * 100) 
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Methods: 


distance 

Returns the current distance measured by the sensor in metres. 
Note that this property will have a value between о and max | 
distance. 


max distance 
As specified in the class constructor, the maximum distance that 
the sensor will measure in metres. 


threshold distance 

As specified in the class constructor, the distance (measured in 
metres) that will trigger the when in range and when out of _ 
range events when crossed. 


when in range 
The function to run when the device changes state from active 
to inactive. 


when out of range 
The function to run when the device changes state from inactive 
to active. 


wait for in range(timeout-None) 
Pause the script until the device is deactivated, or the timeout 
is reached. 


wait for out of range(timeout-None) 
Pause the script until the device is activated, or the timeout 


is reached. 


echo 
Returns the GPIO pin that the sensor's ECHO pin is connected to. 


trigger 
Returns the GPIO pin that the sensor's TRIG pin is connected to. 
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obl DEVICES 


SPI (serial peripheral interface) is a mechanism allowing compatible 
devices to communicate with the Pi. GPIO Zero provides some classes 
for devices, including a range of analogue-to-digital converters... 


[ SPI ARGUMENTS ] 


When constructing an SPI device, there are two schemes 
for specifying which pins it's connected to.. 
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Analogue-to-Digital Converters (ADCs) 


MCP3001: 
gpiozero 


MCP3002: 
gpiozero 


MCP3004: 
gpiozero 


MCP3008 
gpiozero 


MCP3201: 
gpiozero 


MCP3202: 
gpiozero 


MCP3204: 
gpiozero 


MCP3208: 
gpiozero 


MCP3301: 
gpiozero 


MCP3302: 
gpiozero 


MCP3304: 
gpiozero 
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.MCP3001(**spi args) 


.MCP3002(channel-0, differential-False, 


.MCP3884(channel=8, differential=False, 


.MCP3008(channel-0, differential-False, 


.MCP3201(**spi args) 


.MCP3202(channel-0, differential-False, 


.MCP3204(channel-0, differential-False, 


.MCP3208(channel-0, differential-False, 


.MCP3301(**spi args) 


.MCP3302(channel-0, differential-False, 


.MCP3384(channel=8, differential-False, 


**spi args) 


**spi args) 


**spi args) 


**spi args) 


**spi args) 


**spi args) 


**spi args) 


**spi args) 


GPIO Zero supports a range of ADC chips, with varying numbers of 
bits (from 10-bit to 13-bit) and channels (1 to 8). As shown in chapters 
9 and 10, numerous jumper wires are required to connect the ADC 
via a breadboard to the Pi. 
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Methods: 


channel 


The channel to read data from. The MCP3008/3208/3304 have eight 
channels (0-7), while the MCP3004/3204/3302 have four channels 
(0-3), and the MCP3001/3201 only have one channel. The MCP3301 
always operates in differential mode between its two channels, and 


the output value is scaled from -1 to *1. 


differentia 


If True, the device is operated in pseudo-differential mode. In this 
mode, one channel (specified by the channel attribute) is read relative 
to the value of a second channel, informed by the chip's design. 


value 


The current value read from the device, scaled to a value between o 
and 1 (or -1 to +1 for devices operating in differential mode). 


04. BOARDS & 


1 


ACGESSORIES 


To make things even easier, GPIO Zero provides extra support for a range 


of add-on devices 


LEDBoar 


gpiozero.LEDBoard(*pins, pwm=False, active high=True, 


and component collections... 


d 


initial value=False, **named pins) 


This class enables you to control a generic LED board or collection 
of LEDs. The following example turns on all the LEDs on a board 


containing five LI 


EDS attached to GPIO pins 2 through 6: 
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from gpiozero import LEDBoard 


leds - LEDBoard(2, 3, 4, 5, 6) 
leds.on() 


Methods: 


on(*args) 
Turn all the output devices on. 


off(*args) 
Turn all the output devices off. 


blink(on time-1, off time-1, fade in time-0, fade out | 
time-0, n=None, background-True) 
Make all the LEDs turn on and off repeatedly. 


pulse(fade in time-1, fade out time-1, n-None, 
background=True) 
Make the device fade in and out repeatedly. 


toggle(*args) 
Toggle all the output devices. For each device, if it's on, turn it off; 
if it's off, turn it on. 


leds 
A flat tuple of all LEDs contained in this collection (and all sub- 
collections). 


Source 
The iterable to use as a source of values for value. 


source delay 
The delay (measured in seconds) in the loop used to read values 
from source. Defaults to 0.01 seconds. 
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value 
A tuple containing a value for each subordinate device. This property 
can also be set to update the state of all subordinate output devices. 


values 
An infinite iterator of values read from value. 


LEDBarGraph 


gpiozero.LEDBarGraph(*pins, initial value=9) 


As shown in chapter 10, this is a class for controlling a line of LEDs to represent a bar 
graph. Positive values (0 to 1) light the LEDs from first to last. Negative values (-1 to 0) 
light the LEDs from last to first. The following example demonstrates turning on the first 
two and last two LEDs in a board containing five LEDs attached to GPIOs 2 through 6: 


from gpiozero import LEDBarGraph 
from time import sleep 


graph - LEDBarGraph(2, 3, 4, 5, 6) 

graph.value = 2/5 # Light the first two LEDs only 
sleep(1) 

graph.value = -2/5 # Light the last two LEDs only 
sleep(1) 

graph.off() 


Methods: 


on() 


Turn all the output devices on. 


off() 
Turn all the output devices off. 


toggle() 
Toggle all the output devices. For each device, if it's on, turn it off; if it's off, turn it on. 
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leds 
A flat tuple of all LEDs contained in this collection (and all 
sub-collections). 


source 
The iterable to use as a source of values for value. 


source delay 
The delay (measured in seconds) in the loop used to read values from 
Source. Defaults to 0.01 seconds. 


value 

A tuple containing a value for each subordinate device. This property 
can also be set to update the state of all subordinate output devices. 
To light a particular number of LEDs, simply divide that number by 
the total number of LEDs. 


values 
An infinite iterator of values read from value. 


TrafficLights 


gpiozero.TrafficLights(red-None, amber=None, green=None, 
pwm=False, initial value=False) 


Extends LEDBoard for devices containing red, amber, and green LEDs (or 
individual LEDs). The following example initialises a device connected to 
GPIO pins 2, 3, and 4, then lights the amber LED attached to GPIO 3: 


from gpiozero import TrafficLights 


traffic - TrafficLights(2, 3, 4) 
traffic. amber .on() 


Methods: 


These are the same as for the LEDBoard class. 
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PiLITEr ШЕ 


TrafficLights class 
can be used to 
control individual 
red, amber, and 
green LEDs, or 
devices containing 
them 


gpiozero.PiLiter( False, False) 


Extends LEDBoard for the Ciseco Pi-LITEr, a strip of eight very 
bright LEDs. The Pi-LITEr pins are fixed and therefore there's no 
need to specify them. The following example turns on all the LEDs 
of the Pi-LITEr: 


gpiozero PiLiter 


lite = Piliter() 
lite.on() 


Methods: 


These are the same as for the LEDBoard class. 


[ Quick Reference ] MägPi | 95 


Magi 
ESSENTIALS 


SnowPi 


gpiozero.SnowPi(pwm-False, initial value-False) 

Extends LEDBoard for the Ryanteck SnowPi board. Since its pins are 
fixed, there's no need to specify them. The following example turns on 
the eyes, sets the nose pulsing, and the arms blinking: 

from gpiozero import SnowPi 

snowman - SnowPi(pwm-True) 

snowman.eyes.on() 


snowman.nose.pulse() 
snowman.arms.blink() 


Methods: 


These are the same as for the LEDBoard class. 


PiLITEr Bar Graph 


gpiozero.PiLiterBarGraph(pwm-False, initial value-0.0) 


Extends LEDBarGraph to treat the Ciseco Pi-LITEr as an eight-segment 
bar graph. The Pi-LITEr pins are fixed and therefore there's no need to 
specify them. The following example sets the graph value to 0.5: 

from gpiozero import PiLiterBarGraph 

graph - PiLiterBarGraph() 

graph.value - 0.5 


Methods: 


These are the same as for the LEDBarGraph class. 
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PI-TRAFFIC 


gpiozero.PiTraffic(pwm=False, initial value-False) 


Extends TrafficLights for the Low Voltage Labs Pi- Traffic, a vertical 
traffic lights board, when attached to GPIO pins 9, 10, and 11. 
The following example turns on the amber LED: 


from gpiozero import PiTraffic 
traffic - PiTraffic() 
traffic. amber .on() 


Methods: 


These are the same as for the TrafficLights class. 


TrafficLightsBuzzer 


gpiozero.TrafficLightsBuzzer(lights, buzzer, button) 
A generic class for HATs with traffic lights, a button, and a buzzer. 


Methods: 


on() 


Turn all the output devices on. 


off() 
Turn all the output devices off. 


toggle() 
Toggle all the output devices. For each device, if it's on, turn it off; 


if it's off, turn it on. 
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Source 
The iterable to use as a source of values for value. 


source delay 


The delay (measured in seconds) in the loop used to read values from 


source. Defaults to 0.01 seconds. 


value 


A tuple containing a value for each subordinate device. This property 
can also be set to update the state of all subordinate output devices. 


values 
An infinite iterator of values read from value. 


Fish Dish 


gpiozero.FishDish(pwm=False) 


Extends TrafficLightsBuzzer for the Pi Supply Fish Dish, which 
has traffic light LEDs, a button, and a buzzer. Since its pins are fixed, 


button to be pressed on the Fish Dish, then turns on allthe LI 
from gpiozero import FishDish 
fish = FishDish() 


fish.button.wait for press() 
fish.lights.on() 


Methods: 


These are the same as for the TrafficLightsBuzzer class. 
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Traffic HAT 


gpiozero.TrafficHat(pwm-False) 


Extends TrafficLightsBuzzer for the Ryanteck Traffic HAT, which 
has traffic light LEDs, a button, and a buzzer. Since its pins are fixed, 
there's no need to specify them. The following example waits for the 
button to be pressed on the Traffic HAT, then turns on all the LEDs: 


from gpiozero import TrafficHat 
hat - TrafficHat() 
hat.button.wait for press() 
hat.lights.on() 


Methods: 


These are the same as for the TrafficLightsBuzzer class. 


Robot 


gpiozero.Robot(left=None, right=None) 


Designed to control a generic dual-motor robot (as in chapter 11), 

this class is constructed with two tuples representing the forward 

and backward pins of the left and right controllers respectively. For 
example, if the left motor’s controller is connected to GPIOs 4 and 14, 
while the right motor’s controller is connected to GPIOs 17 and 18, then 
the following example will drive the robot forward: 


from gpiozero import Robot 


robot = Robot(left-(4, 14), right=(17, 18)) 
robot.forward() 
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Methods: 


forward(speed-1) 
Drive the robot forward by running both motors forward. 


backward(speed=1) 
Drive the robot backward by running both motors backward. 


left(speed=1) 
Make the robot turn left by running the right motor forward and left 
motor backward. 


right (speed=1) 
Make the robot turn right by running the left motor forward and 
right motor backward. 


reverse() 

Reverse the robot’s current motor directions. If the robot is currently 
running full speed forward, it will run full speed backward. If the 
robot is turning left at half speed, it will turn right at half speed. 

If the robot is currently stopped, it will remain stopped. 


stop() 
Stop the robot. 


Source 
The iterable to use as a source of values for value. 


source delay 
The delay (measured in seconds) in the loop used to read values 
from source. Defaults to 0.01 seconds. 


value 

Represents the motion of the robot as a tuple of (left motor speed, 
right motor speed), with (-1, -1) representing full speed backward, 
(1, 1) representing full speed forward, and (0, 0) representing stopped. 


values 
An infinite iterator of values read from value. 
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Ryanteck MCB Robot 


gpiozero.RyanteckRobot 


Extends Robot for the Ryanteck MCB robot. Since its pins are fixed, 
there's no need to specify them when constructing this class. The 
following example drives the robot forward: 

from gpiozero import RyanteckRobot 

robot - RyanteckRobot() 

robot.forward() 


Methods: 


These are the same as for the Robot class. 


CamJam #3 Kit Robot 


gpiozero.CamJamKitRobot 


Extends Robot for the CamJam EdukKit #3 robot. Since its pins are fixed, 
there's no need to specify them when constructing this class. The 
following example drives the robot forward: 

from gpiozero import CamJamKitRobot 

robot - CamJamKitRobot() 

robot.forward() 


Methods: 


These are the same as for the Robot class. 
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Energenie 


gpiozero.Energenie(socket-None, initial value-False) 


Designed to represent an Energenie socket controller, this class is 
constructed with a socket number and an optional initial state (defaults 
to False, meaning off). Instances of this class can be used to switch 
peripherals on and off. For example: 


from gpiozero import Energenie 


lamp - Energenie(1) 
lamp.on() 


Methods: 


is active 

Returns True if the device is currently active, and False otherwise. 
This property is usually derived from value. Unlike value, this is 
always a Boolean. 


source 
The iterable to use as a source of values for value. 


source delay 

The delay (measured in seconds) in the loop used to read values 
from source. Defaults to 0.01 seconds, which is generally sufficient 
to keep CPU usage to a minimum while providing adequate 
responsiveness. 


values 
An infinite iterator of values read from value. 
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